home *** CD-ROM | disk | FTP | other *** search
/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / languages / c / gnu / english next >
Encoding:
Text File  |  1993-06-25  |  13.3 KB  |  402 lines
  1. GCC for RISC OS
  2. ---------------
  3.  
  4. 0. Installation
  5.    ------------
  6.  
  7. The installation consists of:
  8.  
  9.   1. RUN$Path must be extended with the directory name, which contains the
  10.      GNU C executables. You can also copy them to your library directory.
  11.  
  12.   2. Set the variable CPATH. This variable should contain the directories,
  13.      which contain the header files. For instance:
  14.  
  15.      Set CPATH IDEFS::IDEDisc4.$.DesktopC.Clib
  16.  
  17.      CPATH can contain more than one directory name by using ';' seperators.
  18.   
  19.      For instance:
  20.  
  21.      If your header files are in $.clib.1.h and $.clib.2.h, CPATH must be
  22.      set as follows:
  23.  
  24.      Set CPATH $.clib.1;$.clib.2
  25.     
  26.      You may also want to set the variables:
  27.  
  28.      C_INCLUDE_PATH
  29.      CPLUS_INCLUDE_PATH
  30.      OBJC_INCLUDE_PATH
  31.      OBJCPLUS_INLCUDE_PATH
  32.  
  33.      CPLUS_INCLUDE_PATH and OBJCPLUS_INCLUDE_PATH will be only used during
  34.      compiling c++ sources.
  35.  
  36.   3. You may have to convert Stubs und RISC_OSlib.
  37.  
  38.   4. You must set the variable mulib$Path to the FULL directory name where
  39.      the risclib libraries can be found (e.g. stubsmu and oslib_mu). For
  40.      instance:
  41.  
  42.      Set mulib$path IDEFS::IDEDisc4.$.Temp.GNU-CC.gcc2-3-3.risclib.
  43.  
  44.      The libraries can be found by calling Libraries mulib:stubsmu and
  45.      mulib:oslib_mu
  46.  
  47.   5. The documentation can be found in the 'doc' directory.
  48.  
  49. 1. Prefixes in filenames
  50.    ---------------------
  51.  
  52. Unix expects, in contrary to RISC OS, that files types such as .c .o .cc
  53. are used as extension to the filename (e.g. myfile.c). GCC uses also all
  54. file names in this format. In order to behave correctly under RISC OS,
  55. GCC moves the file type extension to the start of the filename. For instance
  56. 'GCC sample.c' will be 'GCC c.sample'. Note: 'irgend.sample.c' will be
  57. 'c.irgend.sample'. GCC uses these extensions in order to find out the
  58. file type. 
  59.  
  60. The extensions have the following meaning:
  61.  
  62.  .c              C Source
  63.  .cc, .cxx, .C   C++ Source (Note: only .cc can be used with RISC OS)
  64.  .m              objective-C Source (not yet supported)
  65.  .o              object file
  66.  .h              header file
  67.  .i              pre-processed file (cpp output)
  68.  .ii             pre-processed C++ file
  69.  .s              assembler source
  70.  .S              assembler source (needs pre-processing)
  71.  
  72. 2. Options for GCC
  73.    ---------------
  74.  
  75. An exact explanation of the compiler options are given in the file 'invoke'
  76. in the doc directory. Most options are just like with other C compilers.
  77. You must not forget to use the -O or -O2 (optimizing) option. Without these
  78. options you will get less efficient code.
  79.  
  80. Machine dependent options:
  81.  
  82.  -mno-apsc            use the C-call convention for functions.
  83.  -mcoproc             Coprocessor is available (due to code optimizing,
  84.                       works also without one)
  85.  -mpoke-function-name function names for post mortem debugger in code
  86.  
  87. 3. Include files
  88.    -------------
  89.  
  90. For the include files is also the prefix-notation for file typen used. In
  91. the source code can the suffix-notation be used. The pre-processor converts
  92. these file names to prefix notation and recognizes the Unix directory paths.
  93. For instance /usr/include/sys/times.h becomes $.usr.include.sys.h.times,
  94. ../my-header.h becomes ^.h.my-header. The compiler recognizes only the
  95. file extensions .h und .c.
  96.  
  97. Search order for include files:
  98.  
  99.   1. current directory or the directories, which have been entered using
  100.      the -I option 
  101.   2. the directories, which are given by CPATH.
  102.   3. the directories given by C_INCLUDE_PATH (Standard C),
  103.      CPLUS_INCLUDE_PATH (C++), OBJC_INCLUDE_PATH (Objective C) or
  104.      OBJCPLUS_INLCUDE_PATH (Objective C++)
  105.  
  106. The 'environment variables' may contain more directories (by using the
  107. ';' character as seperator). The Unix notation may also be used. However,
  108. different from RISC OS, the '.' or '/' character may not be the last
  109. character in direcory name (the Pre-Processor will do this for you). Also
  110. the '.h' must not be used in the path name.
  111.  
  112. 4. Linker
  113.    ------
  114.  
  115. The linker must be called separately from the compiler (you must also
  116. use the -c option). In order to get 'absolute' code the linker must be
  117. called as follows:
  118.  
  119.  mulink -F -a32768 -osample -C o.sample1 o.sample2 mulib:stubsmu
  120.  settype sample absolute
  121.  
  122. Explanation:
  123.  
  124. mulib$path contains the directory name where 'stubsmu' can be found.
  125.  
  126.  -F       first object file must always be linked (only , when referenced).
  127.           If stubsmu is linked, this option is not particulary necessary,
  128.           because stubsmu has set the Obligatory-Link-Flag (will always be
  129.           linked) and contains a reference to 'main'.
  130.  -a32768  Absolute code with execution address &8000.
  131.  -osample sample will be the output file (Note: no spaces)
  132.  -C       only the code, without header, publics, relocs.
  133.  
  134. If the -a and -C options are not used, a object-file will be produced.
  135.  
  136. Further options:
  137.  
  138.  -x          a list of symbols, moduls and their addresses (e.g. offsets)
  139.              will be given.
  140.  
  141.  -+          link C++ - code. The linker will search for symbol names in a
  142.              C++ fashion and if they could not be found, they are converted
  143.              into standard-C name. For instance:
  144.  
  145.              printf( "%d", 10 )
  146.      
  147.              generates in C++ a assembler call:
  148.           
  149.              ... bl printf__FPci
  150.  
  151.              If a symbol printf__FPci exists, the linker will generate a call
  152.              to this symbol. Otherwise (with the -+ option) the name printf
  153.              will be used (without __F...).
  154.  
  155.  -$<suffix>  the characters, which in C++ symbol names is used between
  156.              the 'normal' name of the function and the type. Default: __F.
  157.  -u       do not print a liste of undefined externals
  158.  
  159. All other options are ignored by RISC OS version (have no meaning).
  160.  
  161. Stubs MUST be linked before the RISC_OSlib is linked. The file which
  162. contains the function main MUST be linked first. In other cases the
  163. order of the object files doesn't matter. Objects which are not referenced
  164. by none of the other object files are simply ignored. For instance:
  165.  
  166.  mulink -F o.sample1 o.sample2 mulib:stubsmu
  167.  
  168. o.sample2 will not be linked, if neither in mulib:stubsmu nor in o.sample1
  169. a function or variable from o.sample1 is referenced.
  170.  
  171. If Stubs are linked, the following message could be printed:
  172.  
  173.  unresolved external(s)
  174.    '__root_stack_size' in module 'Stub$$Code'
  175.    '__RelocCode' in module 'Stub$$Code'
  176.  
  177. Both references are in AOF-files as 'weak binding' defined and don't have
  178. to be declared. Applications will be linked correctly.
  179.  
  180. If the RISC_OSlib is linked, the following message is printed:
  181.  
  182.  warning: double defined public variable(s):
  183.  
  184. Simply ignore this :-)
  185.  
  186. 5. AOFConvert
  187.    ----------
  188.  
  189. AOFConvert is a utility which converts object files in AOF-Format into
  190. the MUPROS format.
  191.  
  192. You have to use it as follows:
  193.  
  194.  AOFConvert -l -osample o.sample
  195.  
  196. The option -l suppresses all warnings (which are not interesting). During
  197. some circumstances you will also have to use the -O option. Then will the
  198. converted object ALWAYS be linked (if it is used somewhere in conjunction
  199. with MULINK, even if no reference is fullfilled).
  200.  
  201. 6. Assembler
  202.    ---------
  203.  
  204. If you like to use the assembler, you are referred to the tex file (in the
  205. doc directory) and the RISC OS PRM's. The assembler is called by using:
  206.  
  207.  as -o o.sample s.sample
  208.         
  209. A object file in MUPROS format will be generated. Note: assembler
  210. instructions must be lower case. Register names may be upper case or
  211. lower case. ARM/MUPROS specific pseudo-instructions:
  212.  
  213.  .objname <name>       the just assembled object will be called
  214.                        <name> (Default: Dateiname)
  215.  .segid <name>         the segment ID becomes <name> (Default: 'code')
  216.  .segattr <'RO'|'RW'>  Read-only or Read-Write Segment (Default: 'RW')
  217.  
  218. At the moment the assembler does not support separate code, data and null
  219. initialised segments (.text, .data, .bss), these will be assembled in
  220. different files.
  221.  
  222. An example of a assembler source code is risclib.s.div-fast. More examples
  223. can be generated using GCC -O -S ...
  224.  
  225. A full list of the assembler instructions (from the source code):
  226.  
  227. /* format of the assembler string :
  228.    
  229.    %<bitfield>r         print as an ARM register
  230.    %<bitfield>f         print a floating point constant if >7 else an
  231.                         fp register
  232.    %c                   print condition code (always bits 28-31)
  233.    %P                   print floating point precision in arithmetic insn
  234.    %Q                   print floating point precision in ldf/stf insn
  235.    %R                   print floating point rounding mode
  236.    %<bitnum>'c          print specified char iff bit is one
  237.    %<bitnum>-<len>'c    print specified char iff bit is one and length of
  238.                         command after c is at least len
  239.    %<bitnum>`c          print specified char iff bit is zero
  240.    %<bitnum>?ab         print a if bit is one else print b
  241.    %p                   print 'p' iff bits 12-15 are 15
  242.    %o                   print operand2 (immediate or register + shift)
  243.    %a                   print address for ldr/str instruction
  244.    %b                   print branch destination
  245.    %A                   print address for ldc/stc/ldf/stf instruction
  246.    %m                   print register mask for ldm/stm instruction
  247.    %s                   print bits 0-23 as swi number/name
  248.    %L                   print ldm type (fd, ea and the like ...)
  249.    %S                   print stm type
  250.    %r                   print adr operand
  251.  
  252. /* ARM instructions */
  253.  
  254. "mul%c%20's %16-19r,%0-3r,%8-11r",
  255. "mla%c%20's %16-19r,%0-3r,%8-11r,%12-15r",
  256. "and%c%20's %12-15r,%16-19r,%o",
  257. "eor%c%20's %12-15r,%16-19r,%o",
  258. "sub%c%20's %12-15r,%16-19r,%o",
  259. "rsb%c%20's %12-15r,%16-19r,%o",
  260. "add%c%20's %12-15r,%16-19r,%o",
  261. "adr%c%20's %12-15r,%r",
  262. "adc%c%20's %12-15r,%16-19r,%o",
  263. "sbc%c%20's %12-15r,%16-19r,%o",
  264. "rsc%c%20's %12-15r,%16-19r,%o",
  265. "tst%c%p %16-19r,%o",
  266. "teq%c%p %16-19r,%o",
  267. "cmp%c%p %16-19r,%o",
  268. "cmn%c%p %16-19r,%o",
  269. "orr%c%20's %12-15r,%16-19r,%o",
  270. "mov%c%20's %12-15r,%o",
  271. "bic%c%20's %12-15r,%16-19r,%o",
  272. "mvn%c%20's %12-15r,%o",
  273. "str%c%22'b %12-15r,%a",
  274. "ldr%c%22'b %12-15r,%a",
  275. "stm%c%S %16-19r%21'!,%m",
  276. "ldm%c%L %16-19r%21'!,%m%22'^",
  277. "b%24-2'l%c%24'l %b",
  278. "swi%c %s",
  279.  
  280. /* Floating point coprocessor instructions */
  281.  
  282. "adf%c%P%R %12-14f,%16-18f,%0-3f",
  283. "muf%c%P%R %12-14f,%16-18f,%0-3f",
  284. "suf%c%P%R %12-14f,%16-18f,%0-3f",
  285. "rsf%c%P%R %12-14f,%16-18f,%0-3f",
  286. "dvf%c%P%R %12-14f,%16-18f,%0-3f",
  287. "rdf%c%P%R %12-14f,%16-18f,%0-3f",
  288. "pow%c%P%R %12-14f,%16-18f,%0-3f",
  289. "rpw%c%P%R %12-14f,%16-18f,%0-3f",
  290. "rmf%c%P%R %12-14f,%16-18f,%0-3f",
  291. "fml%c%P%R %12-14f,%16-18f,%0-3f",
  292. "fdv%c%P%R %12-14f,%16-18f,%0-3f",
  293. "frd%c%P%R %12-14f,%16-18f,%0-3f",
  294. "pol%c%P%R %12-14f,%16-18f,%0-3f",
  295. "mvf%c%P%R %12-14f,%0-3f",
  296. "mnf%c%P%R %12-14f,%0-3f",
  297. "abs%c%P%R %12-14f,%0-3f",
  298. "rnd%c%P%R %12-14f,%0-3f",
  299. "sqt%c%P%R %12-14f,%0-3f",
  300. "log%c%P%R %12-14f,%0-3f",
  301. "lgn%c%P%R %12-14f,%0-3f",
  302. "exp%c%P%R %12-14f,%0-3f",
  303. "sin%c%P%R %12-14f,%0-3f",
  304. "cos%c%P%R %12-14f,%0-3f",
  305. "tan%c%P%R %12-14f,%0-3f",
  306. "asn%c%P%R %12-14f,%0-3f",
  307. "acs%c%P%R %12-14f,%0-3f",
  308. "atn%c%P%R %12-14f,%0-3f",
  309. "flt%c%P%R %16-18f,%12-15r",
  310. "fix%c%P%R %12-15r,%0-2f",
  311. "wfs%c %12-15r",
  312. "rfs%c %12-15r",
  313. "wfc%c %12-15r",
  314. "rfc%c %12-15r",
  315. "cmf%c %16-18f,%0-3f",
  316. "cnf%c %16-18f,%0-3f",
  317. "cmfe%c %16-18f,%0-3f",
  318. "cnfe%c %16-18f,%0-3f",
  319. "stf%c%Q %12-14f,%A",
  320. "ldf%c%Q %12-14f,%A",
  321.  
  322. 6. Stubs / RISC_OSlib
  323.    ------------------
  324.  
  325. With the GNU C/C++ compiler, you should have also the converted versions
  326. of Stubs and RISC_OSlib (stubsmu and oslib_mu in the directory risclib).
  327. If this is not the case, you can generate these libraries by executing
  328. the Obey file risclib.makelibs.
  329.  
  330. Again: link Stubs always before RISC_OSlib.
  331.  
  332. 7. Your own libraries
  333.    ------------------
  334.  
  335. Libraries are constructed as follows:
  336.  
  337.   1. compile single modules
  338.   2. put the objects in one file (e.g. using fappend)
  339.  
  340. BTW:
  341.  
  342.   mulink .... o.sample1 o.sample2
  343.  
  344. is exactly the same as:
  345.  
  346.   fappend o.sample1 o.sample2
  347.   mulink .... o.sample1
  348.                      
  349. Note: if someone has written a number of functions or classes, which 
  350. are very interesting: PLEASE let also other people use them. If this is
  351. the case, contact me. I will try to distribute them. I hope, other people
  352. will respond. 
  353.  
  354. 8. Objective C
  355.    -----------
  356.  
  357. The current RISC OS version of GNU C/C++ does not support objective C.
  358. If you have a need for this, please contact me.
  359.  
  360. 9. "Support"
  361.    ---------
  362.                
  363. In many mailboxes you will find discussions about GNU C/C++. If you
  364. have access to Internet, for instance UUCP-News, you can read the newsgroup
  365. gnu.g++... For RISC OS specific problems I can be contacted at:
  366.  
  367. Thomas Aeby
  368. Graeffet 406
  369. 1735 Giffers
  370. Schweiz
  371. Tel. 037 38 16 00
  372. EMail aeby@uropax.contrib.de
  373.  
  374. 10. Source code
  375.     -----------
  376.  
  377. All source code of the compiler and the assembler are available from
  378. the address above.
  379.  
  380. 11. Floating point arithmetic
  381.     -------------------------
  382.  
  383. Floating point arithmetic can be used. However, is not very well tested.
  384.  
  385. 12. Memory
  386.     ------
  387.  
  388. In order to compile C++ programs, you will need more than 2Mb free memory
  389. (task slot). Standard C uses less memory, but you will still need about
  390. 1-1.2 Mb. Error messages like 'virtual memory exhausted' mean lack of
  391. memory.
  392.  
  393. NOTE: gcc will not work under Virtual (by Nick Smith), because gcc
  394. calls the preprocessor and the 'real' compiler using the 'system' call.
  395. A solution is on its way.
  396.  
  397. 13. Debugger
  398.     --------
  399.  
  400. Sorry, is not supported. On assembler level, you can (of course) make use
  401. of both !DDT and Debug. Source-Level-Debugging' is not supported.
  402.